Getting Started With the Toolkit
================================

.. adapted from datamark

Software Requirements
---------------------

ArcGIS
++++++

Version 3.1.0 of the Oklahoma NG9-1-1 GIS Toolkit requires a license for Esri ArcGIS Pro to be installed on the user’s workstation. Tools have been tested for use in ArcGIS Pro 3.3 and may or may not function properly with other versions of ArcGIS.

Python
++++++

The GIS Toolkit requires Python to be installed on the user’s workstation along with the ArcPy package, which is included with the user’s ArcGIS Pro installation. A Standard license is required. Python 3.11 is installed with ArcGIS Pro 3.3 as part of the ``arcgispro-py3`` environment; the Toolkit may or may not function properly with other versions of Python.

The Toolkit depends on some packages installed by default in the ``arcgispro-py3`` environment, so these dependencies must also be installed if the Toolkit is to be run using a different Python environment.

GIS Toolkit Setup
-----------------

Download the NG9-1-1 GIS Toolkit to the User Workstation
++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The Oklahoma NG9-1-1 GIS Toolkit is available for download from the Oklahoma Geographic Information Council. The Toolkit is delivered as a zip file containing the tools and related documentation.

Unzip the NG9-1-1 GIS Toolkit
+++++++++++++++++++++++++++++

Unzip the NG9-1-1 GIS Toolkit and save it to the user workstation. All files and folders must remain in their original structure for proper operation of the NG9-1-1 GIS Toolkit.

Extract the NG9-1-1 GIS Toolkit to a Local Folder
+++++++++++++++++++++++++++++++++++++++++++++++++

Once the NG9-1-1 GIS Toolkit has been saved to the user workstation, extract it to a local folder on the workstation.

Accessing the Toolkit
+++++++++++++++++++++

The Toolkit is most easily accessed and used by adding the ArcGIS Python Toolbox, ``NG911_GIS_Toolkit_Pro.pyt``, to an ArcGIS Pro project.

Structure of the Toolkit
------------------------

.. danger::

   Do not edit the structure of the files and folders of the Toolkit. Moving, renaming, or otherwise modifying the file and folder structure of the Toolkit may break it.

The Toolkit is comprised of a number of items:

.. csv-table:: Toolkit Contents
   :header-rows: 1

   Item, Location, Purpose, Relevant to...
   ArcGIS Python Toolbox, ``/NG911_GIS_Toolkit_Pro.pyt``, Toolbox containing the tools for use in ArcGIS Pro, |ALL|
   Documentation, ``/Docs``, Toolkit documentation, |ALL|
   Log Files, ``/ng911ok.log``, Generated by using the Toolkit; contains log messages to help with debugging, |REPORTERS| |DEVELOPERS|
   ``ng911ok`` Python Package, ``/ng911ok``, Python scripts used by the Toolbox, |ADVANCED|
   YAML Configuration Files, ``<Various>.yml``, Data files that define certain Toolkit behavior, |DEVELOPERS|
   ``Utilities`` Directory, ``/Utilities``, Additional Python utility scripts and data files, |ADVANCED| |DEVELOPERS|
   Command Line Validation Script, ``/quickvalidate.py``, Standalone Python script for running validation from the command line, |ADVANCED|

.. csv-table:: "Relevant to..." Key
   :header-rows: 1

   Badge, Explanation
   |ALL|, Everyone who uses the Toolkit
   |REPORTERS|, Anyone who is reporting a bug **or seeking support**
   |ADVANCED|, "Advanced users, such as those writing their own scripts"
   |DEVELOPERS|, Developers/maintainers of the Toolkit itself

.. danger::

   Editing the YAML (``.yml``) configuration files may break the Toolkit or result in incorrect behavior.

Python Toolbox
++++++++++++++

.. adapted from datamark

The Oklahoma Next Generation 9-1-1 GIS Toolkit includes GIS data management tools used by local, county, and state GIS and public safety personnel. The Toolkit includes an ArcGIS Python Toolbox made up of the following toolsets:

.. list-table::
   :header-rows: 1

   * - Toolset
     - Purpose
   * - Prep
     - Prepares and standardizes local datasets.
   * - Enhancement
     - Automates and simplifies tasks for creating and updating data.
   * - Validation
     - Ensures compliance with the NG9-1-1 Standards.
   * - MSAG
     - Compares NG911 data to MSAG data.
   * - Comparison
     - Identifies differences between local and state data.
   * - Submission
     - Packages the data to be uploaded to the repository.

Together, these tools support every step of the NG9-1-1 GIS workflow.


.. |ALL| replace:: :bdg-success:`All Users`

.. |REPORTERS| replace:: :bdg-info:`Bug Reporters`

.. |ADVANCED| replace:: :bdg-warning:`Advanced Users`

.. |DEVELOPERS| replace:: :bdg-danger:`Toolkit Developers`
